package io.github.echarts.model.theme;

import io.github.echarts.model.context.ConfigurationContext;

/**
 * 默认值提供者接口
 * <p>
 * 定义了组件配置的默认值处理逻辑，包括应用默认值、确保配置完整性和应用主题。
 * 实现类负责为特定组件类型提供默认配置，支持数据驱动的智能默认值。
 * </p>
 * 
 * @param <T> 配置类型
 */
public interface DefaultValueProvider<T> {
    
    /**
     * 应用默认值到配置对象
     * <p>
     * 仅在配置对象的属性为null时应用默认值，不覆盖用户显式设置的值。
     * 可以根据上下文中的数据特征选择合适的默认值。
     * </p>
     * 
     * @param config 配置对象
     * @param context 配置上下文，包含数据特征等信息
     */
    void applyDefaults(T config, ConfigurationContext context);
    
    /**
     * 检查配置完整性并补全缺失值
     * <p>
     * 确保所有必要的配置项都有值，包括对象嵌套结构中的值。
     * 对于组合配置（如坐标轴、系列等），递归处理子配置项。
     * </p>
     * 
     * @param config 配置对象
     * @param context 配置上下文
     */
    void ensureCompleteness(T config, ConfigurationContext context);
    
    /**
     * 应用主题特定的样式
     * <p>
     * 将主题中定义的视觉样式应用到配置对象，包括颜色、文本样式、线条样式等。
     * 保持对象其他配置项不变，只应用视觉相关的样式。
     * </p>
     * 
     * @param config 配置对象
     * @param theme 主题对象
     */
    void applyTheme(T config, Theme theme);
    
    /**
     * 获取支持的配置类型
     * 
     * @return 支持的配置类类型
     */
    Class<T> getSupportedType();
} 